Tutorial:
Note: all examples in this tutorial use Adobe Photoshop for image editing and Microsoft Notepad for text editing

Tools Needed:
- an MS-DOS text editor, windows "Notepad" works fine
- an image editor that can save in ".gif" format (should be able to manipulate the 256 color palette) Adobe Photoshop is recommended, but very expensive.
- the TWIGZ Engine & SDK

Procedure:

Step 9: Creating Enter, Exit and General Scripts
Step 10: Creating the Dialogue File
Step 11: Creating the Verb File
Step 12: Creation the Inventory Verb File
Step 13: Creating the Default Inventory File

Step 9: Creating Enter, Exit and General Scripts

All aspects of the TWIGZ engine, whether it be animating non-playable characters (NPCs), starting a conversation, manipulating actor costumes, etc., make use of TWIGZ scripting files. Below is a sample script file followed by a thorough explanation of what scripts are and why they are necessary.

5 46 197 349 412 475 1 "Choose Actor",1 "Place Actor",5,99 "Load Costume",1,2,1 "Choose Actor",2 "Place Actor",75,75 "Load Costume",1,1,1 "Set Direction",1,1 "Set ZIndex",1,3 "Set Current Poly",1,2 "Load Script",2 "Fade In" "End Script" 2 "Change BinVar",1,0 "Add To Inventory",4001 "End Script" 3 "Actor Face Actor",1,2 "Say",2,"But you told me to~stay here so nobody~can come in." "Say",1,"Well I want you to go~back to my office and~wait for me there." "Say",2,"You mean lair, right, sir?" "Say",1,"Yes, yes lair,~that's what I meant." "Say",2,"You're not the boss,~you're not even on the~same side of the~wall as me." "Say",1,"So it may seem." "Say",2,"Listen, you're not~getting in here so~just forget it!" "End Script" 4 "Load Script",7 "End Script" 5 "IF BV Less",6,50 "Change BinVar",6,0 "IF BV Greater",1,5 "Set TopX",50 "End Script"

Note:
The first number represents the total number of scripts included in this script file. The following 5 numbers represent file offset at which each script starts (these numbers are calculated by the TWIGZ level maker, part of the TWIGZ SDK). Any single number, alone on a line, represents the start of a script (i.e. a "1" would mean script 1 starts here). All scripts must end with the "End Script" command.

What are scripts?:
Scripts are what drive the TWIGZ Engine. When a level is loaded (i.e. Level "1.lvl"), the script file of that same number is loaded (i.e. Script "1.scr"). The first script in any script file is the "Enter Script" which is automatically run upon loading the level. This script should be used to set up actor positions and costumes, assign scripts to actors, change and edit Bin Variables, etc.

Scripts run in the background while the engine is running. Currently the TWIGZ Engine supports the simultaneous running of 25 scripts at once (more than you should ever need).

How do they work?:
Scripts are executed line by line. When a new line is read the command is interpreted by the engine and then executed.

How are they triggered?:
Scripts can be triggered in a variety of ways. A script can be triggered after interacting with a "hot-spot", at the beginning or end of a conversation, a script can even be triggered from within another script!

What is an Enter Script?:
An Enter Script is the FIRST SCRIPT in a script file. This is automatically loaded when the level is loaded. This should be used to place all actors in their appropriate places, set up their costumes, check and set any BinVars, etc. It can even be set to load other scripts based on logical tests.

What is an Exit Script?:
An exit script is a script that exits the current room and loads another room (by way of the "Load Level" script command). This can be any script number except number 1.

How do animations work?:
Animations are done by way of manipulating an Actor's costume. In order for an animation to run properly the 4 following commands must be used:
1. Choose Actor
2. Set Frames
3. Set Delay
4. Do Animation
5. Stop Animation
The animation will run until the "Loop" parameter of the Do Animation command is finished executing (Note: if this is set to an infinite loop, the animation will not terminate until the level is closed).

How do I create a script?:
There are several, non-complicated steps involved in this process. Before you begin it is recommended that you have a print-out of all the TWIGZ Scripting Commands from the table below.

1. Grab your favorite, simple, MS-DOS text editor (Windows Notepad works fine). If you don't have a favorite you may use edit.exe by loading the TWIGZ Level Editor and clicking on the "Edit Scripts" button.

2. Type the total number of scripts you wish to create followed by an immediate strike of the ENTER key. (NOTE: There CANNOT be any extra spaces at the end of any lines in the script file).

3. Type the script number you wish to work on first.

4. Enter a script command in quotes (Note: these commands ARE case sensitive) followed by a comma (if necessary) and then any appropriate parameters.

5. When you have finished entering all commands, be sure to include the "End Script" command. You may do the same for all other scripts. When you are completely done you can run the TWIGZ Level Editor and click the "Create Script" button to create your script. (Note: make sure all scripts you create are saved in the "SDK\Scripts" folder as ".txt" files).

STOP In order for Script Generation to occur properly you MUST make sure the first number at the start of the script file accounts for the total number of scripts in the file. So if your file has 15 scripts, the first number at the start of the script file MUST be 15!

Below is a list of all the Scripting Commands (PRINT this for your records):

Command	Parameters	Description
Dialogue:
Say	ActorID, Text$	The actor says the text
End Dialogue		This must follow all individual, or sets, of "Say" commands. Can be left out only if the "Say" commands immediately precede an "End Script" command
Costumes:
Choose Actor	Actor ID	Selects Actor(Actor ID) as the current actor
Place Actor	X, Y	Places current actor at x, y
Load Costume	Costume, Set, Image	Sets current actor's current costume, set, and image
Set Frames	Costume, Set, Start Image, End Image	Sets animation frames by costume & set, then by which images to go through (Increasing or Decreasing order)
Do Animation	Loops	Loops = [ (-2) - 'Forward & Back Infinite' | (-1) - 'Forward then Back' | (0) - 'Forward Infinite' | (1) - 'Forward Once' ]
Stop Animation		Ends the animation
Set Delay	Delay	Sets the delay between frames in an animation
Ego Face Actor	ActorID	Turns Twigz toward the actor
Ego Face Camera		Turns Twigz toward the audience Actor(0)
Actor Face Ego	ActorID	Turns the actor toward Twigz
Actor Face Actor	ActorID1, ActorID2	Turns the first actor toward the second actor
Inventory:
Add To Inventory	Inventory ID	Adds corresponding Inventory Object to the inventory based on Inventory ID
General:
Load Level	Level Number	Loads a level
Set TopX	TopX	Sets the Level.TopX to TopX for scrolling
Change BinVar	BinVar Number, Status	Changes BinVar Number's status to BinVar Status
BinVar Status	BinVar Number	Returns the status of that BinVar
Load Script	ActorID, Script Number	Loads a script to be executed, the executes it (If ActorID = 0, the script is a general level script)
End Script		Ends The Script
Close Script		Close Script File
Close Files		Closes all open files at that current time (used before loading a new level)
Fade In		Fades the screen from black to current palette colors
Fade Out		Fades the screen from current palette colors to black
Ego Animating	Value	Pauses all interactivity in game so a scripted animation can run (Value = 0 for FALSE & Value = -1 for TRUE)
Wait	Time	The script hangs at this point for the duration of Time (Time is a SINGLE floating point number)
Enter Script:
Set Current Poly	ActorID, Polygon	Sets the Actor's Path.CurrentPoly value to Polygon (currently ActorID is unnecessary because path-finding only works for the Ego)
Logic:
IF BV Equals	BinVar, Status	IF BinVar = Status THEN execute next line (unless in a BLOCK)
IF BV Less	BinVar, Status	IF BinVar < Status THEN execute next line (unless in a BLOCK)
IF BV Greater	BinVar, Status	IF BinVar > Status THEN execute next line (unless in a BLOCK)
IF BV LE	BinVar, Status	IF BinVar < or = Status THEN execute next line (unless in a BLOCK)
IF BV GE	BinVar, Status	IF BinVar > or = Status THEN execute next line (unless in a BLOCK)
ELSE		If the ELSE of the previous IF statement is true, execute next line (unless in a BLOCK)
BLOCK		Starts a Logic Block
END BLOCK		Ends a Logic Block
BinVar Manipulation:
INC BV	BinVar	Increases the value of the BinVar by 1
DEC BV	BinVar	Decreases the value of the BinVar by 1
Walking:
Actor Walk To	ActorID, X, Y	Actor walks to point as if the mouse was clicked on (X,Y)
Walk To Object	ActorID, ObjectID	Actor walks to a certain object by the object's (WalkToX, WalkToY)
Set Direction	ActorID, Direction	Actor's direction is set to Direction
Set Head Direction	ActorID, Head Direction	Actor's head is set to Head Direction
Set ZIndex	ActorID, ZIndex	Actor's z-index is set to ZIndex

The following is a key for the "Parameters" column in the above table:

Key:
Green	SINGLE floating point number
White	INTEGER

 

 

Back to Top

Step 6: Creating the Dialogue File

Whenever there is a dialogue exchange where the player can select dialogue choices, we call this a "conversation." The TWIGZ Engine loads the appropriate dialogue file for the current room (i.e. Room 1's dialogue file would be "1.dia") and initializes the dialogue engine. Below is a sample of a dialogue file:

1 10 1 5 1,5 "Hello?" "Excuse me." "Guard! On your feet!" "Cheesy's Pizza, I've got two large pepperoni here." "I'll be going now." "","What do you want?!",1,2,2,0 "","What do you want?!",1,2,3,0 "Guard, get on your feet Soldier!","Sir, is that you?",1,2,4,0 "Cheesy's Pizza, I've got two~large pepperoni here.~That'll be $16.95.","Mmmm, pepperoni,~I love pepperoni.",1,2,5,0 "","And be quick about it!",1,2,-1,0 2,1 "I, um, am here to inspect this gate." "I, um, am here to inspect this gate.~Yep, open her right up and~I'll check her out!","Nice try, but I'm not supposed~to let anyone in.~So scram!",1,2,1,0 3,1 "It looks like somehow you locked yourself out." "It looks like somehow you~locked yourself outside~the gate and locked me inside.~You better open up this gate~so we can switch places.","Well, how did that hap --~Wait a second! Nice try.",1,2,1,0 4,1 "You're darn right it's me." "You're darn right it's me.~Why aren't you off somewhere,~patrolling something?","",1,2,1,5 5,1 "...and extra cheese?" "","...and extra cheese, mmmm! Wait a minute, I~didn't order any pizza.~Go on, get outta here!",1,2,1,0

A Dialogue file is best explained by the steps the engine takes to read it, below is an outline of these steps:

The first thing the engine does is load the appropriate dialogue file. The first number it reads represents the Total Conversations stored in the file. If there are 5 conversations in this file then the next 5 numbers would represent the file offset where these conversations begin (this is called the "offset list").

Following the offset list, the conversation data begins. The first number in a conversation represents the conversation number. This is followed by the Total Number of Sets in the conversation. This information makes up the Conversation Header.

Following the Conversation Header is the Set data. All Sets begin with two numbers separated by a comma (Set Number, Total Dialogue Choices). Immediately after this comes the text choices for display in the GUI so the player can click on them (These are not necessarily what the character will say, see below).

What's the purpose of this, you ask? Lets say you are talking to a character who is very dangerous and evil, and he is asking you questions such as "I'm not such a bad guy though, right?" You can have a text choice that reads "Nooo, not too bad for an insane maniac bent on evil world domination." However, when the player clicks on the choice the Ego will say "Of course not!" (This gives you a deeper look into the inner-monologue of the Ego)

After the GUI text choices are read the dialogue engine waits for the users input. When the user clicks on a text choice, the engine goes to the corresponding choice in the file. A text choice looks as follows:

"Guard, get on your feet Soldier!","Sir, is that you?",1,2,4,0

The first string represents the actual text the Ego will say (if the text is the SAME as the GUI text, this can be written as an empty string and the engine will simply use the GUI text). The second string represents the actual text the other Actor will say. The first integer represents the first Actor ID number, the second represents the second Actor ID number, the third represents the next dialogue set to jump to (-1 will cause the Engine to end the conversation), and the final integer represents the script number to execute BEFORE jumping to the next set (0 represents no script).

How do I make a dialogue file?:
All you need to create your own dialogue file is the TWIGZ SDK and your favorite MS-DOS text editor (Microsoft Notepad works just fine). Just type the total number of conversations that will be in this file. For each conversation, start off with an integer representing the conversation number on one line and the total sets on another. For each set, start of with the GUI text choices, one on a line. For each choice type in the text choice data like shown above.

Repeat this process for all conversations in the dialogue file. When you have finished, simply place the text file in the "TWIGZ SDK\Dialogue" folder and run "RoomEdit.exe" and then Click on the "Conversations" Button (or you can just run "Convos.exe"). You will be prompted for the file name to "Load" simply type in the file name WITHOUT the extension (which should be ".txt") and press enter. Next type in the "New" file name to save it as (should be the number of your room). So if the room you are working on is room 5 then you should type "5" as the file name to save it as (the "NEW" file name) and the file "5.dia" will be created.

Back to Top

Step 11: Creating the Verb File

Whenever the Ego interacts with an object (or actor) the engine accesses the ".vrb" file for that room and says the appropriate dialogue. Below is the basic outline for a verb (".vrb") file:

"Open" 10 1,1,1,"I can't open a stick",0 4,4,-1,"It's locked",0 4,5,-1,"I'm gunna open this here gate",0 8,6,1,"Open this well cover?",0 8,6,-1,"It's already open",0 14,7,1,"I'll just slip in this here back door",0 14,7,-1,"It's already open",0 17,8,-1,"I will turn this knob and open the door",0 3001,0,0,"Ey, uh, Fred, uh ...~wanna go bowlin?",0 0,0,0,"I can't open that",0 "Close" 2 1,1,1,"",8 0,0,0,"I can't close that",0 "Pick Up" 4 1,1,1,"Ohhhh, a stick",3 2,2,-1,"I love rocks",4 3002,0,0,"I don't think he'd like that.",0 0,0,0,"I can't pick that up",0 "Look At" 3 3001,0,0,"That's Fred, he's a nice guy!",0 3002,0,0,"That's John, he can hold~his breath for over~10 minutes!",0 0,0,0,"That's a nice thing",0 "Talk To" 2 3001,0,0,"Starting conversation . . .",0,1 0,0,0,"I really don't want to talk right now",0,0 "Use" 1 0,0,0,"I don't think I should",0 "Push" 1 0,0,0,"Not right now",0 "Pull" 1 0,0,0,"No pulling for me right now",0 "Walk To" 2 7,0,0,"I'm leaving the room now!",3 8,0,0,"",3

The ".vrb" file is separated into verbs. Each verb name in quotation marks represents the start of the data for that verb. After each verb name is the total number of statements for that verb. Following that is the list of all the text that will be said by the ego (we call these lines "statements"). Any statement that starts with all zeros, like the one below, is the Default Statement for that verb.

Below is an example of a Default Statement:

0,0,0,"I don't think I should",0

What do all those numbers mean?:
Each "statement" is preceded by three (3) numbers and then followed by another (EXCEPT for "Talk To" that ends with 2 Integers!). A verb statement looks like this:

Object (or Actor) ID, Bin Variable, Bin Var Required Status, "Text", Script Number

A "Talk To" verb statement looks like this:

Object (or Actor) ID, Bin Variable, Bin Var Required Status, "Text", Script Number, Conversation Number

When a object, say Object ID 10, is clicked on with the "Open" verb selected, the engine opens the appropriate verb file (for room 1, it would be "1.vrb") and scans the file until it reaches the "Open" verb. Then it searches for the appropriate Object ID. If the Object ID is found then the engine proceeds to check the appropriate Bin Variable's status with the Required Status. If these two are the same then the Ego will say the appropriate text and the script number (if it is not 0) will be executed.

If all criteria are not met then the Ego simply says the default statement.

How do I create a verb file?:
All verb files can be written in your favorite, simple, MS-DOS text editor (Windows Notepad works fine). Just make sure there are no extra spaces (unless they are in between quotation marks) between the commas separating the different parts of a statement or at the end of a statement. When you are finished save this as a ".vrb" file in your "TWIGZ SDK\Verbs" folder. You can do this from notepad by going to File, Save As, Choosing "All Files" from the "Save as type" drop-down menu. And naming the file "roomnumber.vrb" so if your room is room number 5, then save the file as "5.vrb"

Why is there a tilde ("~") between some of the text in a statement?:
A tilde ("~") represents a new line in a statement's text. Below is an example of a statement with several new line characters:

3002,0,0,"That's John, he can hold~his breath for over~10 minutes!",0

When the Ego says the appropriate text it will appear on the screen as follows:

That's John, he can hold his breath for over 10 minutes!

Where as, without the new line characters it would appear as follows:

That's John, he can hold his breath for over 10 minutes!

Why are some Object IDs above 3000 & 4000?:
Every "object", whether it is an actor, object, or inventory item, is given a unique Global ID Number. All object IDs go from 1 to 3000, all actor IDs go from 3001 to 4000, and all inventory items (once collected and stored in the inventory) go from 4001 to 5000.

Note: When developing an adventure game with the TWIGZ SDK it is recommended that you keep track of which object IDs represent which objects using some sort of database or spreadsheet (Microsoft Excel works fine).

What characters are supported by the TWIGZ Engine for verb files?:
All letters A-Z and a-z, all digits 0-9, and the following special characters: ! $ * , . ? - " [to make a quotation mark ( " )] use the carrot ( ^ ) symbol]. Below is the default font file that is loaded when the engine starts:

Note: When using the Level Editor (included in the TWIGZ SDK) objects, actors and inventory objects can be named with ALL of the above characters and the following additional characters: / # + ; and © (use the "at" (@) symbol to make the copyright symbol).

Back to Top

Step 12: Creating the Inventory Verb File

Whenever an inventory object is selected to use on an object, with an object, or just to be interacted with, the Inventory Verb file for that room is accessed. Inventory Verb files are near identical to regular Verb files with the addition of one variable. Below is an example of a simple Inventory Verb file:

"Give" 3 4001,4002,0,0,"How am i going to do that?",0 4002,3001,0,0,"He probably doesn't want a rock.",0 0,0,0,0,"No!",0 "Open" 1 0,0,0,0,"I can't open that",0 "Close" 1 0,0,0,0,"I can't close that",0 "Pick Up" 2 4001,4001,0,0,"That's a nice stick I picked up.",0 0,0,0,0,"I can't pick that up",0 "Look At" 1 0,0,0,0,"That's a nice thing",0 "Talk To" 1 0,0,0,0,"I really don't want to talk right now",0 "Use" 2 4001,5,0,0,"Put the stick in there?~Yeah, you'd want~to see that!",0 0,0,0,0,"I don't think I should",0 "Push" 1 0,0,0,0,"Not right now",0 "Pull" 1 0,0,0,0,"No pulling for me right now",0

The ".ivb" file is separated into verbs. Each verb name in quotation marks represents the start of the data for that verb. After each verb name is the total number of statements for that verb. Following that is the list of all the text that will be said by the ego (we call these lines "statements"). Any statement that starts with all zeros, like the one below, is the Default Statement for that verb.

Below is an example of a Default Statement:

0,0,0,0,"No pulling for me right now",0

What do all those numbers mean?:
Each "statement" is preceded by three (4) numbers and then followed by another. A verb statement looks like this:

ID1, ID2, Bin Variable, Bin Var Required Status, "Text", Script Number

ID1 represents the Inventory Object ID, ID2 represents the other object that the inventory object is to be used with (this number can be from 1 to 5000, it can be an object, an actor or another inventory item). The Bin Variable, Bin Var Required Status, and Script Number work the same as for a regular verb file.

Note There is no Conversation Number added on for "Talk To" statements, YOU CANNOT START A CONVERSATION WITH YOU INVENTORY! Also note there are NO "Walk To" statements at the end of this file.

If all criteria are not met then the Ego simply says the default statement.

Note: Two unique IDs can only be used when dealing with the verbs: Give & Use. If you want to make the actor say something when he, for example, tries to open inventory object 4001 then you must make ID1 and ID2 both 4001.

How do I create an Inventory Verb File?
All inventory verb files can be written in your favorite, simple, MS-DOS text editor (Windows Notepad works fine). Just make sure there are no extra spaces (unless they are in between quotation marks) between the commas separating the different parts of a statement or at the end of a statement. When you are finished save this as a ".ivb" file in your "TWIGZ SDK\IVerbs" (that's "I VERBS," its hard to see) folder. You can do this from notepad by going to File, Save As, Choosing "All Files" from the "Save as type" drop-down menu. And naming the file "roomnumber.vrb" so if your room is room number 5, then save the file as "5.ivb"

Back to Top

Step 13: Creating the Default Inventory File

 

When the TWIGZ Engine is loaded the "default.inv" (Default Inventory file) is loaded into memory. Below is the structure of the "default.inv" file:

3 "Stick" "Rock" "Key" 40 1 19 0 0 0 0 0 0 207 205 0 0 0 0 0 0 0 0 0 0

The first number is the Total Number of Inventory Items, the next three items are the Names for the items, following that are the Pixel Maps for all the inventory items.

How can I create my own default inventory file?:
All you need is a ".gif" file placed in the "TWIGZ SDK\Images" folder (Note: The ".gif" file must adhere to the GLOBAL PALETTE). Below is a sample default inventory file:

Once you have placed you image file in the "TWIGZ SDK\Gif" folder simply run "RoomEdit.exe" and click on the "Inventory" button. You will be prompted to enter the file name to load. Enter the file name without the ".bs2" extension (this should be saved in your TWIGZ SDK\Images" folder). Individually select each image by left-clicking in the top right corner and moving your mouse to the bottom left and clicking with the right mouse button. After this process you will be prompted to enter the image's name.

Repeat this for all inventory images.

Note: Every time you wish to add an inventory item to the inventory file you must do this process all over. I will release a better inventory program shortly, but for now use this.

When you are finished press "S" to save the file. When prompted, save the file as "default" and it will appear in your TWIGZ SDK folder as "default.inv"

The first image will appear as Inventory Id Number 4001, the second as 4002 and so on. I recommend you keep track of these in a database of spreadsheet somewhere.

Back to Top

Step 14: Test Your Game

You have completed your first room for the TWIGZ Engine. Although there is a lot to do it's really more complicated to write down in tutorial form then to actually do. Once all the graphics and palette is dealt with. The actual room creation process should only take 10-15 minutes maximum. The dialogue, verb, and inventory verb files should only take another 20 - 30 minutes. You just have to get the hang of it.

To run your game, make sure you have the following files in the appropriate directories (note replace the "TWIGZ SDK" folder name with the folder name you have the TWIGZ SDK stored in):

TWIGZ SDK\Dialogue\0.dia

TWIGZ SDK\Verbs\0.vrb

TWIGZ SDK\IVerbs\0.ivb

TWIGZ SDK\Scripts\0.scr

TWIGZ SDK\Levels\0.lvl

TWIGZ SDK\Costumes\0.cos

TWIGZ SDK\default.inv

Now you are ready to test your game, simply run "TWIGZ.exe" and all should be well.

If you have any questions or comments, PLEASE DON'T HESITATE TO ASK. Email me at crazys@shatteredrealmproductions.com and PLEASE tell me if you are creating a game with the TWIGZ Engine, there would be no better reward than to see a complete game created off my engine. Oh and PLEASE, GIVE CREDIT WHERE CREDIT IS DUE ...